### 11.10 Sequence iterators

Sequence iterators are convenience constructs for iterating through statements in a sequence. Given a sequence `SEQ`, here is a typical use of gimple sequence iterators:

         gimple_stmt_iterator gsi;

         for (gsi = gsi_start (seq); !gsi_end_p (gsi); gsi_next (&gsi))
           {
             gimple g = gsi_stmt (gsi);
             /* Do something with gimple statement G.  */
           }

Backward iterations are possible:

                 for (gsi = gsi_last (seq); !gsi_end_p (gsi); gsi_prev (&gsi))

Forward and backward iterations on basic blocks are possible with `gsi_start_bb` and `gsi_last_bb`.

In the documentation below we sometimes refer to enum `gsi_iterator_update`. The valid options for this enumeration are:

- `GSI_NEW_STMT` Only valid when a single statement is added. Move the iterator to it.
- `GSI_SAME_STMT` Leave the iterator at the same statement.
- `GSI_CONTINUE_LINKING` Move iterator to whatever position is suitable for linking other statements in the same direction.

Below is a list of the functions used to manipulate and use statement iterators.

— GIMPLE function: gimple_stmt_iterator gsi_start (gimple_seq seq)

> Return a new iterator pointing to the sequence `SEQ`'s first statement. If `SEQ` is empty, the iterator's basic block is `NULL`. Use `gsi_start_bb` instead when the iterator needs to always have the correct basic block set.

— GIMPLE function: gimple_stmt_iterator gsi_start_bb (basic_block bb)

> Return a new iterator pointing to the first statement in basic block `BB`.

— GIMPLE function: gimple_stmt_iterator gsi_last (gimple_seq seq)

> Return a new iterator initially pointing to the last statement of sequence `SEQ`. If `SEQ` is empty, the iterator's basic block is `NULL`. Use `gsi_last_bb` instead when the iterator needs to always have the correct basic block set.

— GIMPLE function: gimple_stmt_iterator gsi_last_bb (basic_block bb)

> Return a new iterator pointing to the last statement in basic block `BB`.

— GIMPLE function: bool gsi_end_p (gimple_stmt_iterator i)

> Return `TRUE` if at the end of `I`.

— GIMPLE function: bool gsi_one_before_end_p (gimple_stmt_iterator i)

> Return `TRUE` if we're one statement before the end of `I`.

— GIMPLE function: void gsi_next (gimple_stmt_iterator *i)

> Advance the iterator to the next gimple statement.

— GIMPLE function: void gsi_prev (gimple_stmt_iterator *i)

> Advance the iterator to the previous gimple statement.

— GIMPLE function: gimple gsi_stmt (gimple_stmt_iterator i)

> Return the current stmt.

— GIMPLE function: gimple_stmt_iterator gsi_after_labels (basic_block bb)

> Return a block statement iterator that points to the first non-label statement in block `BB`.

— GIMPLE function: gimple * gsi_stmt_ptr (gimple_stmt_iterator *i)

> Return a pointer to the current stmt.

— GIMPLE function: basic_block gsi_bb (gimple_stmt_iterator i)

> Return the basic block associated with this iterator.

— GIMPLE function: gimple_seq gsi_seq (gimple_stmt_iterator i)

> Return the sequence associated with this iterator.

— GIMPLE function: void gsi_remove (gimple_stmt_iterator *i, bool remove_eh_info)

> Remove the current stmt from the sequence. The iterator is updated to point to the next statement. When `REMOVE_EH_INFO` is true we remove the statement pointed to by iterator `I` from the `EH` tables. Otherwise we do not modify the `EH` tables. Generally, `REMOVE_EH_INFO` should be true when the statement is going to be removed from the `IL` and not reinserted elsewhere.

— GIMPLE function: void gsi_link_seq_before (gimple_stmt_iterator *i, gimple_seq seq, enum gsi_iterator_update mode)

> Links the sequence of statements `SEQ` before the statement pointed by iterator `I`. `MODE` indicates what to do with the iterator after insertion (see `enum gsi_iterator_update` above).

— GIMPLE function: void gsi_link_before (gimple_stmt_iterator *i, gimple g, enum gsi_iterator_update mode)

> Links statement `G` before the statement pointed-to by iterator `I`. Updates iterator `I` according to `MODE`.

— GIMPLE function: void gsi_link_seq_after (gimple_stmt_iterator *i, gimple_seq seq, enum gsi_iterator_update mode)

> Links sequence `SEQ` after the statement pointed-to by iterator `I`. `MODE` is as in `gsi_insert_after`.

— GIMPLE function: void gsi_link_after (gimple_stmt_iterator *i, gimple g, enum gsi_iterator_update mode)

> Links statement `G` after the statement pointed-to by iterator `I`. `MODE` is as in `gsi_insert_after`.

— GIMPLE function: gimple_seq gsi_split_seq_after (gimple_stmt_iterator i)

> Move all statements in the sequence after `I` to a new sequence. Return this new sequence.

— GIMPLE function: gimple_seq gsi_split_seq_before (gimple_stmt_iterator *i)

> Move all statements in the sequence before `I` to a new sequence. Return this new sequence.

— GIMPLE function: void gsi_replace (gimple_stmt_iterator *i, gimple stmt, bool update_eh_info)

> Replace the statement pointed-to by `I` to `STMT`. If `UPDATE_EH_INFO` is true, the exception handling information of the original statement is moved to the new statement.

— GIMPLE function: void gsi_insert_before (gimple_stmt_iterator *i, gimple stmt, enum gsi_iterator_update mode)

> Insert statement `STMT` before the statement pointed-to by iterator `I`, update `STMT`'s basic block and scan it for new operands. `MODE` specifies how to update iterator `I` after insertion (see enum `gsi_iterator_update`).

— GIMPLE function: void gsi_insert_seq_before (gimple_stmt_iterator *i, gimple_seq seq, enum gsi_iterator_update mode)

> Like `gsi_insert_before`, but for all the statements in `SEQ`.

— GIMPLE function: void gsi_insert_after (gimple_stmt_iterator *i, gimple stmt, enum gsi_iterator_update mode)

> Insert statement `STMT` after the statement pointed-to by iterator `I`, update `STMT`'s basic block and scan it for new operands. `MODE` specifies how to update iterator `I` after insertion (see enum `gsi_iterator_update`).

— GIMPLE function: void gsi_insert_seq_after (gimple_stmt_iterator *i, gimple_seq seq, enum gsi_iterator_update mode)

> Like `gsi_insert_after`, but for all the statements in `SEQ`.

— GIMPLE function: gimple_stmt_iterator gsi_for_stmt (gimple stmt)

> Finds iterator for `STMT`.

— GIMPLE function: void gsi_move_after (gimple_stmt_iterator *from, gimple_stmt_iterator *to)

> Move the statement at `FROM` so it comes right after the statement at `TO`.

— GIMPLE function: void gsi_move_before (gimple_stmt_iterator *from, gimple_stmt_iterator *to)

> Move the statement at `FROM` so it comes right before the statement at `TO`.

— GIMPLE function: void gsi_move_to_bb_end (gimple_stmt_iterator *from, basic_block bb)

> Move the statement at `FROM` to the end of basic block `BB`.

— GIMPLE function: void gsi_insert_on_edge (edge e, gimple stmt)

> Add `STMT` to the pending list of edge `E`. No actual insertion is made until a call to `gsi_commit_edge_inserts`() is made.

— GIMPLE function: void gsi_insert_seq_on_edge (edge e, gimple_seq seq)

> Add the sequence of statements in `SEQ` to the pending list of edge `E`. No actual insertion is made until a call to `gsi_commit_edge_inserts`() is made.

— GIMPLE function: basic_block gsi_insert_on_edge_immediate (edge e, gimple stmt)

> Similar to `gsi_insert_on_edge`+`gsi_commit_edge_inserts`. If a new block has to be created, it is returned.

— GIMPLE function: void gsi_commit_one_edge_insert (edge e, basic_block *new_bb)

> Commit insertions pending at edge `E`. If a new block is created, set `NEW_BB` to this block, otherwise set it to `NULL`.

— GIMPLE function: void gsi_commit_edge_inserts (void)

> This routine will commit all pending edge insertions, creating any new basic blocks which are necessary.